Skip to content

MkCommentedCode

Show source on GitHub

Node which displays a list of code / comment blocks for given code.

Description

Lines beginning with # are shown in dedicated blocks and can be used to inline-explain the code. Lines can be hidden by ending a line with "##".

Example: From text

Jinja

{{
"
# Comment sections automatically get converted to non-codeblock sections.
# That way you can explain your code in-line.

# ## you can use headers.

some_code = 1 + 2

# !!! note
#     Admonitions and everything else work, too.
#

" | MkCommentedCode
}}

Python

MkCommentedCode(
    "\n# Comment sections automatically get converted to non-codeblock sections.\n# That way you can explain your code in-line.\n\n# ## you can use headers.\n\nsome_code = 1 + 2\n\n# !!! note\n#     Admonitions and everything else work, too.\n#\n\n"
)

Comment sections automatically get converted to non-codeblock sections. That way you can explain your code in-line.

you can use headers.

some_code = 1 + 2

Note

Admonitions and everything else work, too.

<div class="speech bottom" markdown="1">
Comment sections automatically get converted to non-codeblock sections.
That way you can explain your code in-line.
## you can use headers.
</div>
```` {.python }
some_code = 1 + 2
````
<div class="speech bottom" markdown="1">
!!! note
    Admonitions and everything else work, too.

</div>

<div class="speech bottom">
<p>Comment sections automatically get converted to non-codeblock sections.
That way you can explain your code in-line.</p>
<h2 id="you-can-use-headers">you can use headers.</h2>
</div>
<div class="language-python highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="n">some_code</span> <span class="o">=</span> <span class="mi">1</span> <span class="o">+</span> <span class="mi">2</span>
</span></code></pre></div>
<div class="speech bottom">
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Admonitions and everything else work, too.</p>
</div>
</div>

MkCommentedCode
├── MkSpeechBubble('Comment sections automatically get converted to...lain your code in-line.\n## you can use headers.')
│   ╰── MkText('Comment sections automatically get converted to non-codeblock sections.\nThat way you can explain your code in-line.\n## you can use headers.')
├── MkCode('some_code = 1 + 2')
│   ╰── MkText('some_code = 1 + 2')
╰── MkSpeechBubble('!!! note\n    Admonitions and everything else work, too.\n')
    ╰── MkText('!!! note\n    Admonitions and everything else work, too.\n')

Example: From function

Jinja

{{ mk.MkCommentedCode.create_example_page | MkCommentedCode }}

Python

MkCommentedCode(<bound method MkCommentedCode.create_example_page of <class 'mknodes.templatenodes.mkcommentedcode.<locals>.MkCommentedCode'>>)


    @classmethod
    def create_example_page(cls, page):
Comment sections automatically get converted to non-codeblock sections. That way you can explain your code in-line.

you can use headers.

        page += MkCommentedCode(MkCommentedCode.create_example_page)

Note

Admonitions and everything else work, too.

        page += MkCommentedCode(MkCommentedCode.create_example_page, style="admonition")


```` {.python }
    @classmethod
    def create_example_page(cls, page):
````
<div class="speech bottom" markdown="1">
Comment sections automatically get converted to non-codeblock sections.
That way you can explain your code in-line.
## you can use headers.
</div>
```` {.python }
        page += MkCommentedCode(MkCommentedCode.create_example_page)
````
<div class="speech bottom" markdown="1">
!!! note
    Admonitions and everything else work, too.

</div>
```` {.python }
        page += MkCommentedCode(MkCommentedCode.create_example_page, style="admonition")
````

<div class="language-python highlight"><pre><span></span><code><span id="__span-0-1"><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>    <span class="nd">@classmethod</span>
</span><span id="__span-0-2"><a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a>    <span class="k">def</span> <span class="nf">create_example_page</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">page</span><span class="p">):</span>
</span></code></pre></div>
<div class="speech bottom">
<p>Comment sections automatically get converted to non-codeblock sections.
That way you can explain your code in-line.</p>
<h2 id="you-can-use-headers">you can use headers.</h2>
</div>
<div class="language-python highlight"><pre><span></span><code><span id="__span-1-1"><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a>        <span class="n">page</span> <span class="o">+=</span> <span class="n">MkCommentedCode</span><span class="p">(</span><span class="n">MkCommentedCode</span><span class="o">.</span><span class="n">create_example_page</span><span class="p">)</span>
</span></code></pre></div>
<div class="speech bottom">
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Admonitions and everything else work, too.</p>
</div>
</div>
<div class="language-python highlight"><pre><span></span><code><span id="__span-2-1"><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a>        <span class="n">page</span> <span class="o">+=</span> <span class="n">MkCommentedCode</span><span class="p">(</span><span class="n">MkCommentedCode</span><span class="o">.</span><span class="n">create_example_page</span><span class="p">,</span> <span class="n">style</span><span class="o">=</span><span class="s2">&quot;admonition&quot;</span><span class="p">)</span>
</span></code></pre></div>

MkCommentedCode
├── MkCode('    @classmethod\n    def create_example_page(cls, page):')
│   ╰── MkText('    @classmethod\n    def create_example_page(cls, page):')
├── MkSpeechBubble('Comment sections automatically get converted to...lain your code in-line.\n## you can use headers.')
│   ╰── MkText('Comment sections automatically get converted to non-codeblock sections.\nThat way you can explain your code in-line.\n## you can use headers.')
├── MkCode('        page += MkCommentedCode(MkCommentedCode.create_example_page)')
│   ╰── MkText('        page += MkCommentedCode(MkCommentedCode.create_example_page)')
├── MkSpeechBubble('!!! note\n    Admonitions and everything else work, too.\n')
│   ╰── MkText('!!! note\n    Admonitions and everything else work, too.\n')
╰── MkCode('        page += MkCommentedCode(MkCommentedCode.create_example_page, style="admonition")')
    ╰── MkText('        page += MkCommentedCode(MkCommentedCode.create_example_page, style="admonition")')

Bases: MkTemplate

__init__ 

__init__(
    code: str | datatypes.HasCodeType,
    language: str = "py",
    *,
    linenums: int | None = None,
    style: Literal["text", "admonition", "bubble"] = "bubble",
    **kwargs: Any
)

Parameters:

Name Type Description Default
code str | HasCodeType

Code to show

 required
language str

language for syntax highlighting

 'py'
linenums int | None

If set, use as start linenumber

 None
style Literal['text', 'admonition', 'bubble']

Comment style

 'bubble'
kwargs Any

Keyword arguments passed to parent

 {}
Name Children Inherits
MkTemplate
mknodes.templatenodes.mktemplate
Node representing a jinja template.		 
graph TD
  94854582944528["mkcommentedcode.MkCommentedCode"]
  94854582782240["mktemplate.MkTemplate"]
  94854582919984["mkcontainer.MkContainer"]
  94854582916880["mknode.MkNode"]
  94854582838576["node.Node"]
  140544995341632["builtins.object"]
  94854582782240 --> 94854582944528
  94854582919984 --> 94854582782240
  94854582916880 --> 94854582919984
  94854582838576 --> 94854582916880
  140544995341632 --> 94854582838576
/home/runner/work/mknodes/mknodes/mknodes/templatenodes/mkcommentedcode/metadata.toml
[metadata]
icon = "mdi:code-json"
name = "MkCommentedCode"
status = "new"
group = "documentation"
virtual_children = true

[examples.from_text]
title = "From text"
jinja = """
{{
"
# Comment sections automatically get converted to non-codeblock sections.
# That way you can explain your code in-line.

# ## you can use headers.

some_code = 1 + 2

# !!! note
#     Admonitions and everything else work, too.
#

" | MkCommentedCode
}}
"""


[examples.from_function]
title = "From function"
jinja = """
{{ mk.MkCommentedCode.create_example_page | MkCommentedCode }}
"""

[output.markdown]
template = """
{% for section in inspecthelpers.iter_code_sections(node.code, node.linenums) %}
{% if section.typ == "code" %}
{{ section.code | MkCode(linenums=section.start_line) }}
{% elif node.style == "text" %}
{{ section.code }}
{% elif node.style == "bubble" %}
{{ section.code | MkSpeechBubble }}
{% elif node.style == "admonition" %}
{{ section.code | MkAdmonition }}
{% endif %}
{% endfor %}
"""
mknodes.templatenodes.mkcommentedcode.MkCommentedCode
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
class MkCommentedCode(mktemplate.MkTemplate):
    """Node which displays a list of code / comment blocks for given code.

    Lines beginning with # are shown in dedicated blocks and can be used to
    inline-explain the code. Lines can be hidden by ending a line with "##".
    """

    ICON = "material/code-json"
    STATUS = "new"
    VIRTUAL_CHILDREN = True

    def __init__(
        self,
        code: str | datatypes.HasCodeType,
        language: str = "py",
        *,
        linenums: int | None = None,
        style: Literal["text", "admonition", "bubble"] = "bubble",
        **kwargs: Any,
    ):
        """Constructor.

        Arguments:
            code: Code to show
            language: language for syntax highlighting
            linenums: If set, use as start linenumber
            style: Comment style
            kwargs: Keyword arguments passed to parent
        """
        self._code = code
        self.language = language
        self.title = ""
        self.linenums = linenums
        self.style = style
        super().__init__(template="output/markdown/template", **kwargs)

    @property
    def code(self) -> str:
        match self._code:
            case str():
                return self._code
            case _:
                return inspecthelpers.get_source(self._code)

    @classmethod
    def create_example_page(cls, page):
        # Comment sections automatically get converted to non-codeblock sections.
        # That way you can explain your code in-line.

        # ## you can use headers.

        page += MkCommentedCode(MkCommentedCode.create_example_page)
        # !!! note
        #     Admonitions and everything else work, too.
        #
        page += MkCommentedCode(MkCommentedCode.create_example_page, style="admonition")